.TH DYLIBPROF 1 "March 19, 2002" "Apple Computer, Inc."
.SH NAME
dylibprof \- control the shared pc sampling of a dynamic shared library
.SH SYNOPSIS
dylibprof [\-e | \-d] | [\-c | \-r | \-b | \-h | \-p [\-o <file>] <dylib>]
.SH DESCRIPTION
Dylibprof along with the server /usr/libexec/profileServer allows shared
program counter sampling of a dynamic shared library across all the programs
that use the library.
.PP
To use
.IR dylibprof (1),
/usr/libexec/profileServer must be running.  So first start
/usr/libexec/profileServer and leave it running in the back ground:
.nf
	% /usr/libexec/profileServer >& /dev/console &
.fi
.PP
/usr/libexec/profileServer starts up with shared pc sampling disabled.  It should
not be left running with shared pc sampling enabled if no sampling is being
done as every launch of a program that uses the dynamic linker is effected.
This is true even to a small extent if there no libraries being sampled.
.PP
If you need to profile from boot up for all processes then the following line
can be added to /etc/bootstrap.conf:
.nf
	server "/usr/libexec/profileServer" services NSProfileServer NSProfileControl;
.PP
Before any dynamic shared library can be sampled sampling must be enabled as
follows:
.nf
	% dylibprof \-e
.fi
.PP
It can then later be disabled when no more sampling is to be done with:
.nf
	% dylibprof \-d
.fi
.SH EXAMPLE
To sample the dynamic shared library /System/Library/Frameworks/System.framework/Versions/B/System for example requires
the following steps.  First create a sample buffer for the library:
.nf
	% dylibprof \-c /System/Library/Frameworks/System.framework/Versions/B/System
.fi
.PP
Then begin the sampling:
.nf
	% dylibprof \-b /System/Library/Frameworks/System.framework/Versions/B/System
.fi
After this programs launched using this library will be part of the shared
pc sampling.  Typically what would be done is to then use the system normally
for a number of hours.
.PP
Then to halt the sampling:
.nf
	% dylibprof \-h /System/Library/Frameworks/System.framework/Versions/B/System
.fi
.PP
The profiling output file (a gmon.out file) can be created with:
.nf
	% dylibprof \-p \-o /tmp/gmon.out /System/Library/Frameworks/System.framework/Versions/B/System
.fi
.PP
Using the profiling output file and the library a profile listing and a time
based order file (time.order) can be created with:
.IR gprof (1):
.nf
	% gprof \-S /System/Library/Frameworks/System.framework/Versions/B/System /tmp/gmon.out
.PP
When no more sampling for this library is to be done the sample buffer can be
removed with:
.nf
	% dylibprof \-r /System/Library/Frameworks/System.framework/Versions/B/System
.fi
.PP
The options are:
.TP
.B  \-e
Enable shared program counter sampling for dynamic libraries.
.TP
.B  \-d
Disable shared program counter sampling for dynamic libraries.
.TP
.B  \-c
Create a pc sample buffer for the library.
.TP
.B  \-b
Begin sampling for programs subsequently launched using the library.
.TP
.B  \-h
Halt sampling for programs subsequently launched using the library.
.TP
.B  \-p
Produce a profiling output file (a gmon.out file) for the library.
.TP
.B  \-r
Remove the pc sample buffer for the library.
.TP
.BI  \-o " name"
Use the file
.I name
instead of gmon.out when producing the profiling output file with the
.B \-p
above.
.SH FILES
.ta 2.5i
gmon.out	
profile output file
.br
/var/tmp/profile/profile.XXXXXX	
the sample buffer file
.SH "SEE ALSO"
gprof(1)
